Release 10.1A: OpenEdge Development:
Progress 4GL Reference

ON STOP phrase

Describes the processing that occurs when the STOP condition occurs during a block. This condition occurs when a user presses STOP, a STOP statement is executed, or certain internal conditions occur within Progress. The STOP key is usually mapped to CTRL+BREAK (Windows) or CTRL+C (UNIX). By default, the STOP condition undoes all active transactions and returns to the startup procedure or the Procedure Editor.

Syntax 

ON STOP UNDO
  [ label1 ]
  [     , LEAVE [ label2 ]
     |  , NEXT [ label2 ]
     |  , RETRY [ label1 ]
     |  , RETURN { ERROR | NO-APPLY } [ return-string ]
  ]

label1

The name of the block whose processing you want to undo. If you do not name a block with label1, ON STOP UNDO undoes the processing of the block started by the statement that contains the ON STOP phrase.

LEAVE [ label2 ]

Indicates that after undoing the processing of a block, Progress leaves the block labeled label2. If you do not name a block, Progress leaves the block labeled with label1.

NEXT [ label2 ]

Indicates that after undoing the processing of a block, Progress executes the next iteration of the block you name with the label2 option. If you do not name a block with the NEXT option, Progress executes the next iteration of the block labeled with label1.

RETRY [ label1 ]

Indicates that after undoing the processing of a block, Progress repeats the same iteration of the block you name with the label1 option.

RETRY is the default processing if you do not use LEAVE, NEXT, RETRY, or RETURN.

RETURN [ ERROR | NO-APPLY ]

Returns to the calling procedure, or if there is no calling procedure, returns to the Progress Editor. Specifying ERROR causes the ERROR condition in the calling procedure. This causes the current subtransaction to be undone. You cannot specify ERROR within a user-interface trigger block. You can specify the NO-APPLY option only within a user-interface trigger block to prevent Progress from performing the default behavior for that event. For example, the default behavior for an character code key press in a fill-in field is to echo the character in the field.

return-string

If you specify return-string, the string you provide is passed to the calling procedure. That procedure can use the RETURN-VALUE function to read the returned value.

Examples

This procedure lets you update the credit-limit field for each customer. If you enter a value greater than 100,000, the program raises the STOP condition. Since you specified an UNDO, RETRY for a STOP, the procedure starts the iteration over and allows you to enter another value.

r-ostop.p 
FOR EACH customer ON STOP UNDO, RETRY:
   DISPLAY cust-num name credit-limit.
   UPDATE credit-limit.
   IF credit-limit > 100000
   THEN STOP.
END.

The ON STOP phrase is especially useful to trap the STOP condition that results when a user cancels out of a record lock conflict in an application. The r-ostop2.p procedure is a simple record navigation and update utility that finds Salesrep records with the SHARE-LOCK condition. The user can update the values of a Salesrep record in the frame and choose the Assign button to assign the new values to the database. If the user attempts to update a Salesrep record that another user already has in the SHARE-LOCK condition, the r-ostop2.p procedure freezes as a result of the record locking conflict. Progress displays a message asking the user to wait for the other user to relinquish the lock on the record or to press the STOP key to abort the operation.

By default, the STOP key aborts the procedure. The ON STOP phrase on the DO TRANSACTION block in the r-ostop2.p procedure captures the STOP condition and returns control to the procedure.

r-ostop2.p 
DEFINE BUTTON buta LABEL "Find Next".
DEFINE BUTTON butb LABEL "Assign".
DEFINE BUTTON butc LABEL "Done".
DEFINE VARIABLE methRtn AS LOGICAL NO-UNDO.

DEFINE FRAME a
  Salesrep.Sales-rep SKIP Salesrep.Rep-Name SKIP Salesrep.Region SKIP 
  Month-Quota[1] Month-Quota[7] SKIP 
  Month-Quota[2] Month-Quota[8] SKIP
  Month-Quota[3] Month-Quota[9] SKIP 
  Month-Quota[4] Month-Quota[10] SKIP 
  Month-Quota[5] Month-Quota[11] SKIP 
  Month-Quota[6] Month-Quota[12] SKIP(1)     
  buta     butb    Butc
  WITH 1 DOWN NO-BOX SIDE-LABELS.

/*******TRIGGERS*******/
ON CHOOSE OF buta DO:
  FIND NEXT Salesrep SHARE-LOCK.
  IF NOT AVAILABLE(Salesrep) THEN MESSAGE "No Next Salesrep".
  DISPLAY Salesrep WITH FRAME a.
END.

ON CHOOSE OF butb DO:
  DO TRANSACTION ON STOP UNDO, LEAVE:
    ASSIGN Salesrep.Sales-rep Salesrep.Rep-Name Salesrep.Region.
  END.
END.

ON CHOOSE OF butc DO:
  APPLY "ENDKEY" TO FRAME a.
END.

/*******MAIN BLOCK*******/
FIND FIRST Salesrep SHARE-LOCK.
DISPLAY Salesrep WITH FRAME a.
ENABLE ALL WITH FRAME a.
WAIT-FOR ENDKEY OF FRAME a FOCUS buta.

See also

ON ENDKEY phrase, ON ERROR phrase, ON QUIT phrase, RETURN statement, RETURN-VALUE function, STOP statement

Copyright © 2005 Progress Software Corporation
 www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095